//+------------------------------------------------------------------+
//|                                                    SignalAMA.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include <Expert/ExpertSignal.h>    // 专家顾问信号基类（提供信号生成框架）

// wizard description start（MQL5 策略向导描述，用于识别类信息与参数）
//+------------------------------------------------------------------+
//| 类功能描述                                                       |
//| Title=基于自适应移动平均线（Adaptive Moving Average）的交易信号    |
//| Type=SignalAdvanced                                              |
//| Name=Adaptive Moving Average                                     |
//| ShortName=AMA                                                    |
//| Class=CSignalAMA                                                 |
//| Page=signal_ama                                                  |
//| Parameter=PeriodMA,int,10,平均周期（AMA 核心周期参数）             |
//| Parameter=PeriodFast,int,2,快速EMA周期（AMA 灵敏度调节）           |
//| Parameter=PeriodSlow,int,30,慢速EMA周期（AMA 稳定性调节）          |
//| Parameter=Shift,int,0,时间偏移（指标线相对于K线的偏移量）          |
//| Parameter=Applied,ENUM_APPLIED_PRICE,PRICE_CLOSE,应用价格（计算AMA的基础价格）|
//+------------------------------------------------------------------+
// wizard description end

//+------------------------------------------------------------------+
//| CSignalAMA 类：基于自适应移动平均线（AMA）的交易信号生成器          |
//| 核心能力：继承自 CExpertSignal，通过调用 AMA 指标，结合价格（开/高/低/收） |
//|           与 AMA 线的位置关系、交叉形态及指标趋势（斜率），生成4类多空信号， |
//|           支持通过“信号权重”调整不同形态的优先级，适配趋势/震荡行情       |
//| 核心逻辑：AMA 是“自适应”均线（ volatility 越大，平滑系数越小，反应越快），  |
//|           信号基于“价格与 AMA 线的相对位置”“交叉方向”“穿破形态”判断，       |
//|           兼顾趋势跟踪（交叉信号）与震荡过滤（位置信号）                  |
//| 适用场景：中短线趋势交易（AMA 擅长自适应不同行情节奏），适合外汇、股票、期货等 |
//|           品种，可单独使用或与动量指标（如 MACD、RSI）配合提升信号质量      |
//+------------------------------------------------------------------+
class CSignalAMA : public CExpertSignal
  {
protected:
   // 核心组件与参数（保护，子类可访问）
   CiAMA             m_ma;             // AMA 指标对象（封装自适应移动平均线的计算与数据读取）
   // AMA 指标可调参数（与指标原生参数对应，默认配置兼顾灵敏度与稳定性）
   int               m_ma_period;      // 平均周期（AMA 核心周期，默认10，值越大均线越平滑）
   int               m_period_fast;    // 快速 EMA 周期（调节灵敏度，默认2，值越小反应越快）
   int               m_period_slow;    // 慢速 EMA 周期（调节稳定性，默认30，值越大反应越慢）
   int               m_ma_shift;       // 时间偏移（指标线右移/左移，默认0，无偏移）
   ENUM_APPLIED_PRICE m_ma_applied;    // 应用价格（计算AMA的基础价格，默认PRICE_CLOSE，即收盘价）
   // 市场形态信号权重（0-100，值越大信号优先级越高，默认配置突出交叉与穿破信号）
   int               m_pattern_0;      // 形态0权重：价格在AMA线预期侧（如多单需收盘价在AMA上方）
   int               m_pattern_1;      // 形态1权重：价格反向交叉AMA线（如多单时收盘价从下向上穿AMA，但AMA向下）
   int               m_pattern_2;      // 形态2权重：价格同向交叉AMA线（如多单时收盘价从下向上穿AMA，且AMA向上）
   int               m_pattern_3;      // 形态3权重：价格穿破AMA线（如多单时开盘价在AMA上方，但最低价短暂跌破AMA）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化 AMA 信号生成器
    * @details 1. 初始化 AMA 指标对象及默认参数（周期、偏移、应用价格等）；
    *          2. 设置默认信号权重（形态0=10，形态1=70，形态2=100，形态3=60）；
    *          3. 启用价格序列（开盘/最高/最低/收盘），为信号判断提供数据；
    *          4. 继承父类 CExpertSignal 的信号框架初始化
    */
                     CSignalAMA(void);

   /**
    * @brief 析构函数：清理 AMA 信号生成器资源
    * @details 释放 AMA 指标对象占用的内存，依赖父类析构逻辑完成信号框架资源清理
    */
                    ~CSignalAMA(void);

   //----------------------------------------------------------------
   // AMA 指标参数配置：修改指标核心参数（外部调用接口）
   //----------------------------------------------------------------
   /**
    * @brief 设置 AMA 平均周期（核心参数）
    * @param value [in] 周期值（需>0，建议5-30，值越大均线越平滑，趋势跟踪能力越强）
    */
   void              PeriodMA(int value);

   /**
    * @brief 设置 AMA 快速 EMA 周期（灵敏度调节）
    * @param value [in] 周期值（需>0，建议1-5，值越小指标对价格变化反应越快）
    */
   void              PeriodFast(int value);

   /**
    * @brief 设置 AMA 慢速 EMA 周期（稳定性调节）
    * @param value [in] 周期值（需>0，建议20-50，值越大指标越稳定，滞后性越强）
    */
   void              PeriodSlow(int value);

   /**
    * @brief 设置 AMA 时间偏移（指标线位置调节）
    * @param value [in] 偏移值（正数=指标线右移，负数=左移，默认0，无偏移）
    */
   void              Shift(int value);

   /**
    * @brief 设置 AMA 应用价格（计算基础）
    * @param value [in] 价格类型（ENUM_APPLIED_PRICE 枚举，如 PRICE_CLOSE=收盘价，PRICE_MEDIAN=中位价）
    */
   void              Applied(ENUM_APPLIED_PRICE value);

   //----------------------------------------------------------------
   // 信号权重配置：修改不同市场形态的信号强度（外部调用接口）
   //----------------------------------------------------------------
   /**
    * @brief 设置形态0（价格在AMA线预期侧）的信号权重
    * @param value [in] 权重值（0-100，建议10-30，值越大越重视价格与AMA的基础位置关系）
    */
   void              Pattern_0(int value);

   /**
    * @brief 设置形态1（价格反向交叉AMA线）的信号权重
    * @param value [in] 权重值（0-100，建议50-80，值越大越重视“价格交叉但指标趋势反向”的信号）
    */
   void              Pattern_1(int value);

   /**
    * @brief 设置形态2（价格同向交叉AMA线）的信号权重
    * @param value [in] 权重值（0-100，建议80-100，值越大越重视“价格交叉且指标趋势同向”的强信号）
    */
   void              Pattern_2(int value);

   /**
    * @brief 设置形态3（价格穿破AMA线）的信号权重
    * @param value [in] 权重值（0-100，建议40-70，值越大越重视“价格短暂穿破AMA后回归”的信号）
    */
   void              Pattern_3(int value);

   //----------------------------------------------------------------
   // 参数验证：确保指标参数与信号配置有效（信号生成前提）
   //----------------------------------------------------------------
   /**
    * @brief 验证 AMA 指标参数与信号配置的有效性
    * @return bool - 验证结果：true=所有参数有效，false=存在无效参数（如周期≤0）
    * @note 验证逻辑：
    *       1. 先调用父类 ValidationSettings() 验证信号框架基础参数（如品种、周期）；
    *       2. 额外验证 AMA 平均周期（m_ma_period）是否>0，若无效则输出错误日志并返回false；
    *       3. 其他指标参数（快速/慢速周期、偏移等）由指标内部验证，此处仅做基础检查
    */
   virtual bool      ValidationSettings(void);

   //----------------------------------------------------------------
   // 指标初始化：创建并注册 AMA 指标（信号生成的前提）
   //----------------------------------------------------------------
   /**
    * @brief 初始化 AMA 指标及信号所需的价格序列数据
    * @param indicators [in] 指标集合对象（用于管理所有策略用到的指标，如 AMA、RSI 等）
    * @return bool - 初始化结果：true=成功（AMA 指标创建+注册到指标集合），false=失败
    * @note 调用流程：
    *       1. 先调用父类 InitIndicators() 完成基础信号框架与价格序列初始化；
    *       2. 调用内部 InitMA() 方法创建 AMA 指标，绑定当前品种、周期及参数；
    *       3. 若指标创建失败（如参数无效、品种不支持），返回 false 并终止信号生成
    */
   virtual bool      InitIndicators(CIndicators *indicators);

   //----------------------------------------------------------------
   // 信号判断核心方法：生成多空信号权重（策略决策依据）
   //----------------------------------------------------------------
   /**
    * @brief 判断当前市场是否满足多单（买入）开仓条件，返回信号权重
    * @return int - 多单信号权重（0-100，0=无信号，值越大信号越强烈）
    * @note 核心判断逻辑（基于价格与 AMA 线的关系）：
    *       1. 形态0：收盘价在 AMA 上方 → 基础看涨信号，权重=m_pattern_0；
    *       2. 形态1：收盘价从下向上穿 AMA，但 AMA 向下（反向交叉）→ 谨慎看涨信号，权重=m_pattern_1；
    *       3. 形态2：收盘价从下向上穿 AMA，且 AMA 向上（同向交叉）→ 强看涨信号，权重=m_pattern_2；
    *       4. 形态3：开盘价在 AMA 上方，最低价短暂跌破 AMA 后回归 → 回调买入信号，权重=m_pattern_3；
    *       5. 最终返回当前满足条件的最大权重（同一时间仅取最强信号）
    */
   virtual int       LongCondition(void);

   /**
    * @brief 判断当前市场是否满足空单（卖出）开仓条件，返回信号权重
    * @return int - 空单信号权重（0-100，0=无信号，值越大信号越强烈）
    * @note 核心判断逻辑（与多单相反，基于价格与 AMA 线的关系）：
    *       1. 形态0：收盘价在 AMA 下方 → 基础看跌信号，权重=m_pattern_0；
    *       2. 形态1：收盘价从上向下穿 AMA，但 AMA 向上（反向交叉）→ 谨慎看跌信号，权重=m_pattern_1；
    *       3. 形态2：收盘价从上向下穿 AMA，且 AMA 向下（同向交叉）→ 强看跌信号，权重=m_pattern_2；
    *       4. 形态3：开盘价在 AMA 下方，最高价短暂突破 AMA 后回归 → 反弹卖出信号，权重=m_pattern_3；
    *       5. 最终返回当前满足条件的最大权重（同一时间仅取最强信号）
    */
   virtual int       ShortCondition(void);

protected:
   //----------------------------------------------------------------
   // 内部辅助方法：AMA 指标初始化（仅内部调用）
   //----------------------------------------------------------------
   /**
    * @brief 创建并初始化 AMA 指标（绑定品种、周期、参数，注册到指标集合）
    * @param indicators [in] 指标集合对象（用于管理 AMA 指标）
    * @return bool - 初始化结果：true=成功（指标创建+参数配置完成），false=失败
    * @note 内部流程：
    *       1. 检查指标集合指针有效性；
    *       2. 将 AMA 指标对象（m_ma）添加到指标集合；
    *       3. 调用 m_ma.Create() 绑定当前交易品种、周期及指标参数（平均周期、快慢周期等）；
    *       4. 若添加或创建失败，输出错误日志并返回 false
    */
   bool              InitMA(CIndicators *indicators);

   //----------------------------------------------------------------
   // 数据读取：快捷获取 AMA 指标与价格的核心数据（保护，子类可直接调用）
   //----------------------------------------------------------------
   /**
    * @brief 获取指定索引的 AMA 指标值
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - AMA 指标值（反映当前趋势方向与强度）
    */
   double            MA(int ind);

   /**
    * @brief 计算指定索引K线的 AMA 指标差值（当前K线 - 前一根K线，即指标趋势判断依据）
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - AMA 差值（>0=指标向上，<0=指标向下，=0=趋势平稳）
    */
   double            DiffMA(int ind);

   /**
    * @brief 计算指定索引K线的“开盘价与 AMA 差值”（位置关系判断依据）
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - 差值（>0=开盘价在AMA上方，<0=开盘价在AMA下方）
    */
   double            DiffOpenMA(int ind);

   /**
    * @brief 计算指定索引K线的“最高价与 AMA 差值”（穿破形态判断依据）
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - 差值（>0=最高价在AMA上方，<0=最高价在AMA下方）
    */
   double            DiffHighMA(int ind);

   /**
    * @brief 计算指定索引K线的“最低价与 AMA 差值”（穿破形态判断依据）
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - 差值（>0=最低价在AMA上方，<0=最低价在AMA下方）
    */
   double            DiffLowMA(int ind);

   /**
    * @brief 计算指定索引K线的“收盘价与 AMA 差值”（核心位置关系判断依据）
    * @param ind [in] 索引（0=当前K线，1=前一根K线，以此类推）
    * @return double - 差值（>0=收盘价在AMA上方，<0=收盘价在AMA下方）
    */
   double            DiffCloseMA(int ind);
  };
//+------------------------------------------------------------------+